# `ponder.config.ts` [API reference]

:::tip
  This is a low-level reference. For an introduction, visit the
  different config sections: [Chains](/docs/config/chains), [Contracts](/docs/config/contracts), [Accounts](/docs/config/accounts), [Block intervals](/docs/config/block-intervals).
:::

The `ponder.config.ts` file defines chain IDs, RPC URLs, contract addresses & ABIs, and database configuration.

## File requirements

The `ponder.config.ts` file must **default export** the object returned by `createConfig`.

{/* prettier-ignore */}
```ts [ponder.config.ts] {1,4}
import { createConfig } from "ponder";

export default createConfig({
  chains: { /* ... */ },
  contracts: { /* ... */ },
});
```

By default, `ponder dev` and `start` look for `ponder.config.ts` in the current working directory. Use the `--config-file` CLI option to specify a different path.

## `createConfig`

### `database`

Here is the logic Ponder uses to determine which database to use:

- If the `database.kind` option is specified, use the specified database.
- If the `DATABASE_URL` environment variable is defined, use Postgres with that connection string.
- If `DATABASE_URL` is not defined, use PGlite.

| field    |           type           |                                          |
| :------- | :----------------------: | :--------------------------------------- |
| **kind** | `"pglite" \| "postgres"` | **Default: See above.** Database to use. |

#### PGlite

| field         |    type    |                                                                                 |
| :------------ | :--------: | :------------------------------------------------------------------------------ |
| **kind**      | `"pglite"` |                                                                                 |
| **directory** |  `string`  | **Default: `.ponder/pglite`**. Directory path to use for PGlite database files. |

```ts [ponder.config.ts] {4-7}
import { createConfig } from "ponder";

export default createConfig({
  database: {
    kind: "pglite",
    directory: "./.ponder/pglite",
  },
  // ...
});
```

#### Postgres

| field                |                        type                         |                                                                           |
| :------------------- | :-------------------------------------------------: | :------------------------------------------------------------------------ |
| **kind**             |                    `"postgres"`                     |                                                                           |
| **connectionString** |                      `string`                       | **Default: `DATABASE_URL` env var**. Postgres database connection string. |
| **poolConfig**       | [`PoolConfig`](https://node-postgres.com/apis/pool) | **Default: `{ max: 30 }`**. Pool configuration passed to `node-postgres`. |

```ts [ponder.config.ts] {4-10}
import { createConfig } from "ponder";

export default createConfig({
  database: {
    kind: "postgres",
    connectionString: "postgresql://user:password@localhost:5432/dbname",
    poolConfig: {
      max: 100,
      ssl: true,
    },
  },
  // ...
});
```

### `ordering`

Specifies how events across multiple chains should be ordered. For single-chain apps, `ordering` has no effect.

#### Usage

```ts [ponder.config.ts] {4}
import { createConfig } from "ponder";

export default createConfig({
  ordering: "multichain",
  chains: { /* ... */ },
  // ... more config
});
```

#### Parameters

| field        |             type              |                                                      |
| :----------- | :---------------------------: | :--------------------------------------------------- |
| **ordering** | `"omnichain" \| "multichain"` | **Default:** `"omnichain"`. Event ordering strategy. |

#### Guarantees

The omnichain and multichain ordering strategies offer different guarantees. Multichain ordering is generally faster, but will fail or produce a non-deterministic database state if your indexing logic attempts to access the same database row(s) from multiple chains.

|                                      | Omnichain (default)                                                         | Multichain                                                 |
| :----------------------------------- | :-------------------------------------------------------------------------- | :--------------------------------------------------------- |
| Event order for any individual chain | Deterministic, by EVM execution                                             | Deterministic, by EVM execution                            |
| Event order across chains            | Deterministic, by (block timestamp, chain ID, block number)                 | Non-deterministic, no ordering guarantee                   |
| Realtime indexing latency            | Medium-high, must wait for the slowest chain to maintain ordering guarantee | Low, each chain indexes blocks as soon as they arrive      |
| Indexing logic constraints           | None                                                                        | Must avoid cross-chain writes **or** use commutative logic |
| Use cases                            | Bridges, cross-chain contract calls, global constraints                     | Same protocol deployed to multiple chains                  |

### `chains`

An object mapping chain names to chain configuration.

:::warning
  Most Ponder apps require a paid RPC provider plan to avoid rate limits.
:::

#### Usage

```ts [ponder.config.ts]
import { createConfig } from "ponder";
import { BlitmapAbi } from "./abis/Blitmap";

export default createConfig({
  chains: { // [!code focus]
    mainnet: { // [!code focus]
      id: 1, // [!code focus]
      rpc: process.env.PONDER_RPC_URL_1, // [!code focus]
      ws: process.env.PONDER_WS_URL_1, // [!code focus]
    }, // [!code focus]
  }, // [!code focus]
  // ...
});
```

#### Parameters

| field                    |    type                            |                                                                                                                                            |
| :----------------------- | :---------------------------------:| :----------------------------------------------------------------------------------------------------------------------------------------- |
| **name**                 |  `string`                          | **Required**. A unique name for the chain. Must be unique across all chains. _Provided as the object property name._                       |
| **id**                   |  `number`                          | **Required**. The [chain ID](https://chainlist.org) for the chain.                                                                         |
| **rpc**                  |  `string \| string[] \| Transport` | **Required**. One or more RPC endpoints or a Viem [Transport](https://viem.sh/docs/clients/transports/http) e.g. `http` or `fallback`.|
| **ws**                   |  `string`                          | **Default: `undefined`**. A webSocket endpoint for realtime indexing on this chain.                                                         |
| **pollingInterval**      |  `number`                          | **Default: `1_000`**. Frequency (in ms) used when polling for new events on this chain.                                                    |
| **disableCache**         |  `boolean`                         | **Default: `false`**. Disables the RPC request cache. Use when indexing a [local node](/docs/guides/foundry) like Anvil.                   |


### `contracts`

An object mapping contract names to contract configuration. Ponder will fetch RPC data and run indexing functions according to the options you provide.

#### Usage

```ts [ponder.config.ts]
import { createConfig } from "ponder";
import { BlitmapAbi } from "./abis/Blitmap";

export default createConfig({
  contracts: { // [!code focus]
    Blitmap: { // [!code focus]
      abi: BlitmapAbi, // [!code focus]
      chain: "mainnet", // [!code focus]
      address: "0x8d04a8c79cEB0889Bdd12acdF3Fa9D207eD3Ff63", // [!code focus]
      startBlock: 12439123, // [!code focus]
    }, // [!code focus]
  }, // [!code focus]
  // ...
});
```

#### Parameters

| field                          |                  type                   |                                                                                                                                                                                                                                        |
| :----------------------------- | :-------------------------------------: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **name**                       |                `string`                 | **Required**. A unique name for the smart contract. Must be unique across all contracts. _Provided as the object property name._                                                                                                       |
| **abi**                        |              `abitype.Abi`              | **Required**. The contract [ABI](https://docs.soliditylang.org/en/v0.8.17/abi-spec.html) as an array as const. Must be asserted as constant, see [ABIType documentation](https://abitype.dev/guide/getting-started#usage) for details. |
| **chain**                    |        `string \| ChainConfig`        | **Required**. The name of the chain this contract is deployed to. References the `chains` field. Also supports [multiple chains](/docs/config/contracts#multiple-chains).                                                |
| **address**                    | `0x{string} \| 0x{string}[] \| Factory` | **Default: `undefined`**. One or more contract addresses or factory configuration.                                                                                                                                                     |
| **startBlock**                 |          `number \| "latest"`           | **Default: `0`**. Block number or tag to start indexing. Usually set to the contract deployment block number.                                                                                                                          |
| **endBlock**                   |          `number \| "latest"`           | **Default: `undefined`**. Block number or tag to stop indexing. If this field is specified, the contract will not be indexed in realtime. This field can be used alongside `startBlock` to index a specific block range.               |
| **filter**                     |         [`Filter`](#filter)             | **Default: `undefined`**. Event filter criteria. [Read more](/docs/config/contracts#filter-by-indexed-parameter-value).                                                                                                                               |
| **includeTransactionReceipts** |                `boolean`                | **Default: `false`**. If this field is `true`, `transactionReceipt` will be included in `event`.                                                                                                                                       |
| **includeCallTraces**          |                `boolean`                | **Default: `false`**. If this field is `true`, each function in the abi will be available as an indexing function event name. [Read more](/docs/guides/call-traces).                                            |


#### `filter`

:::tip
  The `filter` option is typically only necessary if you have not specified an
  `address`. By default, Ponder only fetches and indexes events for which you
  have registered an indexing function.
:::

The `filter` option is used to filter event logs by argument value. [Read more](/docs/config/contracts#filter-by-indexed-parameter-value) about log filters.

| field     |         type         |                                                                                                                                       |
| :-------- | :------------------: | :------------------------------------------------------------------------------------------------------------------------------------ |
| **event** | `string \| string[]` | **Required**. One or more event names present in the provided ABI.                                                                    |
| **args**  |       `object`       | **Required**. An object containing indexed argument values to filter for. Only allowed if **one** event name was provided in `event`. |

### `accounts`

An object mapping account names to account configuration. Accounts are used to index transactions or native transfers.

#### Usage

```ts [ponder.config.ts]
import { createConfig } from "ponder";

export default createConfig({
  accounts: { // [!code focus]
    coinbasePrime: { // [!code focus]
      chain: "mainnet", // [!code focus]
      address: "0xCD531Ae9EFCCE479654c4926dec5F6209531Ca7b", // [!code focus]
      startBlock: 12111233, // [!code focus]
    }, // [!code focus]
  }, // [!code focus]
  // ...
});
```

#### Parameters

| field                          |                  type                   |                                                                                                                                                                                                                         |
| :----------------------------- | :-------------------------------------: | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **name**                       |                `string`                 | **Required**. A unique name for the smart contract. Must be unique across all contracts. _Provided as the object property name._                                                                                        |
| **chain**                    |                `string`                 | **Required**. The name of the chain this contract is deployed to. References the `chains` field. Also supports [multiple chains](/docs/config/contracts#chain).                                 |
| **address**                    | `0x{string} \| 0x{string}[] \| Factory` | **Default: `undefined`**. One or more contract addresses or factory configuration.                                                                                                                                      |
| **startBlock**                 |                `number`                 | **Default: `0`**. Block number to start syncing events.                                                                                                                                                                 |
| **endBlock**                   |                `number`                 | **Default: `undefined`**. Block number to stop syncing events. If this field is specified, the contract will not be indexed in realtime. This field can be used alongside `startBlock` to index a specific block range. |
| **includeTransactionReceipts** |                `boolean`                | **Default: `false`**. If this field is `true`, `transactionReceipt` will be included in `event`.                                                                                                                        |


### `blocks`

An object mapping block interval names to block interval configuration.

#### Usage

```ts [ponder.config.ts]
import { createConfig } from "ponder";

export default createConfig({
  blocks: { // [!code focus]
    ChainlinkPriceOracle: { // [!code focus]
      chain: "mainnet", // [!code focus]
      startBlock: 19_750_000, // [!code focus]
      interval: 5, // [!code focus] every minute
    }, // [!code focus]
  }, // [!code focus]
  // ...
});
```

#### Parameters

| field     |                         type                         |                                                                                            |
| :-------- | :--------------------------------------------------: | :----------------------------------------------------------------------------------------- |
| **name**  |                `string`                | **Required**. A unique name for the block interval. Must be unique across all block intervals. _Provided as the object property name._ |
| **chain** |                `string`                | **Required**. The name of the chain this block interval is deployed to. References the `chains` field. Also supports [multiple chains](/docs/config/contracts#chain). |
| **startBlock** |                `number`                | **Default: `0`**. Block number to start syncing events. |
| **endBlock** |                `number`                | **Default: `undefined`**. Block number to stop syncing events. If this field is specified, the contract will not be indexed in realtime. This field can be used alongside `startBlock` to index a specific block range. |
| **interval** |                `number`                | **Default: `0`**. The interval between blocks to index. |

## `factory`

Specifies a list of addresses collected from decoded event logs. Both [`contracts`](#contracts) and [`accounts`](#accounts) support `factory()` in their `address` field. [Read more](/docs/guides/factory) in the factory pattern guide.

| field         |                         type                         |                                                                                            |
| :------------ | :--------------------------------------------------: | :----------------------------------------------------------------------------------------- |
| **address**   |             `0x{string} \| 0x{string}[]`             | **Required**. Address of the factory contract that creates instances of this contract.     |
| **event**     | [`AbiEvent`](https://abitype.dev/api/types#abievent) | **Required**. ABI item of the event that announces the creation of a new child contract.   |
| **parameter** |                       `string`                       | **Required**. Name of the parameter within `event` that contains child contract addresses. |

```ts [ponder.config.ts] {8-14}
import { createConfig, factory } from "ponder"; // [!code focus]

export default createConfig({
  contracts: {
    uniswapV2: {
      // ...
      address: factory({ // [!code focus]
        address: "0x5C69bEe701ef814a2B6a3EDD4B1652CB9cc5aA6f", // [!code focus]
        event: parseAbiItem( // [!code focus]
          "event PairCreated(address indexed token0, address indexed token1, address pair, uint256)" // [!code focus]
        ), // [!code focus]
        parameter: "pair", // [!code focus]
      }), // [!code focus]
    },
  },
  // ...
});
```

## Types

The `ponder` package exports several utility types. Use these types to maintain type safety when generating config options dynamically.

### DatabaseConfig

```ts [ponder.config.ts] {1,6}
import { createConfig, type DatabaseConfig } from "ponder"; // [!code focus]

const database = { // [!code focus]
  kind: "postgres", // [!code focus]
  connectionString: process.env.DATABASE_URL, // [!code focus]
} as const satisfies DatabaseConfig; // [!code focus]

export default createConfig({
  database,
  // ...
});
```

### ChainConfig

```ts [ponder.config.ts]
import { createConfig, type ChainConfig } from "ponder"; // [!code focus]

const mainnet = { // [!code focus]
  id: 1, // [!code focus]
  rpc: process.env.PONDER_RPC_URL_1, // [!code focus]
  ws: process.env.PONDER_WS_URL_1, // [!code focus]
} as const satisfies ChainConfig; // [!code focus]

export default createConfig({
  chains: {
    mainnet,
  }
  // ...
});
```

### ContractConfig

```ts [ponder.config.ts] {1}
import { createConfig, type ContractConfig } from "ponder"; // [!code focus]
import { Erc20Abi } from "./abis/Erc20Abi.ts";

const Erc20 = { // [!code focus]
  chain: "mainnet" // [!code focus]
  abi: Erc20Abi, // [!code focus]
  address: "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2", // [!code focus]
} as const satisfies ContractConfig; // [!code focus]

export default createConfig({
  contracts: {
    Erc20,
  },
  // ...
});
```

### BlockConfig

```ts [ponder.config.ts]
import { createConfig, type BlockConfig } from "ponder"; // [!code focus]

const ChainlinkPriceOracle = { // [!code focus]
  chain: "mainnet", // [!code focus]
  startBlock: 19_750_000, // [!code focus]
  interval: 5, // [!code focus]
} as const satisfies BlockConfig; // [!code focus]

export default createConfig({
  blocks: {
    ChainlinkPriceOracle,
  },
  // ...
});
```
